﻿// -----------------------------------------------------------------------
// <copyright file="IPapService.cs" company="Zen Design Corp">
// TODO: Update copyright text.
// </copyright>
// -----------------------------------------------------------------------

namespace Zen.BlackBerry.Pap
{
	using System.Collections.Specialized;
	using System.Threading.Tasks;
	using Zen.BlackBerry.Common;
	using Zen.BlackBerry.Pap.Control;
	using Zen.BlackBerry.Pap.Parser;

	/// <summary>
	/// Interface defining push operations to send PAP 2.1/2.0 XML to a
	/// Push Proxy Gateway (PPG) and parse the PAP XML responses.
	/// </summary>
	public interface IPapService
	{
		/// <summary>
		/// Sends a cancel request using the attributes in the
		/// <paramref name="cancelMessage"/>.
		/// </summary>
		/// <param name="userName">
		/// The username of the Push Initiator (for a public (BIS) push, this
		/// would be the application id; for an enterprise (BES) push this
		/// might be null).
		/// </param>
		/// <param name="password">
		/// The password of the Push Initiator (for a public (BIS) push, this
		/// would be the application password; for an enterprise (BES) push
		/// this might be null).
		/// </param>
		/// <param name="cancelMessage">
		/// The cancel message attributes needed to construct the PAP request.
		/// </param>
		/// <returns>
		/// A task that when complete will contain the PAP response from the
		/// cancel request.
		/// </returns>
		Task<CancelResponse> Cancel(
			string userName,
			string password,
			CancelMessageControl cancelMessage);

		/// <summary>
		/// Pushes the specified user name.
		/// </summary>
		/// <param name="userName">
		/// The username of the Push Initiator (for a public (BIS) push, this
		/// would be the application id; for an enterprise (BES) push this
		/// might be null).
		/// </param>
		/// <param name="password">
		/// The password of the Push Initiator (for a public (BIS) push, this
		/// would be the application password; for an enterprise (BES) push
		/// this might be null).
		/// </param>
		/// <param name="destination">
		/// For a public (BIS) push, the application id to push the content to;
		/// for an enterprise (BES) push, the application port to push the
		/// content to.
		/// </param>
		/// <param name="pushMessage">
		/// The push message attributes needed to construct the PAP request.
		/// </param>
		/// <param name="content">The content of the push message.</param>
		/// <returns>
		/// A task that when complete will contain the PAP response from the
		/// push request.
		/// </returns>
		Task<PushResponse> Push(
			string userName,
			string password,
			string destination,
			PushMessageControl pushMessage,
			Content content);

		/// <summary>
		/// Sends a status query request using the attributes in the
		/// <paramref name="statusMessage"/>.
		/// </summary>
		/// <param name="userName">
		/// The username of the Push Initiator (for a public (BIS) push, this
		/// would be the application id; for an enterprise (BES) push this
		/// might be null).
		/// </param>
		/// <param name="password">
		/// The password of the Push Initiator (for a public (BIS) push, this
		/// would be the application password; for an enterprise (BES) push
		/// this might be null).
		/// </param>
		/// <param name="statusMessage">
		/// The status message attributes needed to construct the PAP request.
		/// </param>
		/// <returns>
		/// A task that when complete will contain the PAP response from the
		/// status query request.
		/// </returns>
		Task<StatusQueryResponse> StatusQuery(
			string userName,
			string password,
			StatusQueryMessageControl statusMessage);

		/// <summary>
		/// Subscriptions the query.
		/// </summary>
		/// <param name="userName">
		/// The username of the Push Initiator (for a public (BIS) push, this
		/// would be the application id; for an enterprise (BES) push this
		/// might be null).
		/// </param>
		/// <param name="password">
		/// The password of the Push Initiator (for a public (BIS) push, this
		/// would be the application password; for an enterprise (BES) push
		/// this might be null).
		/// </param>
		/// <param name="subscriptionMessage">
		/// The subscription message attributes needed to construct the PAP
		/// request.
		/// </param>
		/// <returns>
		/// A task that when complete will contain the PAP response from the
		/// subscription query request.
		/// </returns>
		Task<SubscriptionQueryResponse> SubscriptionQuery(
			string userName,
			string password,
			SubscriptionQueryControl subscriptionMessage);

		/// <summary>
		/// Called when a result notification message is received from the PPG
		/// (for example by the host service or website).
		/// </summary>
		/// <param name="resultMessage">
		/// PAP result notification XML message.
		/// </param>
		/// <param name="requestParameters">
		/// The HTTP request parameters sent by the PPG.
		/// </param>
		/// <returns>
		/// A <see cref="T:ResultNotificationResponseControl"/> object to be
		/// sent to the PPG.
		/// </returns>
		ResultNotificationResponseControl ReceiveNotification(
			ResultNotification resultMessage,
			NameValueCollection requestParameters);
	}
}
